Define the Sandbox Provider protocol in one file - #521

Summary

AGENTS.md gives each boundary exactly one protocol: one code file and one document. Support is learned only through declarations, never through type assertions. The Core–Sandbox Provider boundary was spread over five files (sandbox_provider.go, suspension.go, selection.go, configuration.go, runtimeobs/source.go). Every interface was already required by a reflection check, yet callers still discovered support by casting, 28 times. This is T1a in the architecture audit.

• sandbox_provider.go is the protocol file.
  • SandboxProvider covers the allocation lifecycle, the nine checkpoint methods and Observe. Every method is required at compile time, and ProviderOperations declares which ones are supported. A reflection test keeps the operation groups equal to the interface's method set.
  • ConfigurationAdapter is the setup-time half: decode, encode, normalize, DiscoverConfiguration, DiscoverSelection and VerifyCredential, each declared in ConfigurationRequirements. The registry checks a declaration before every call, and turns "unsupported" from an operation declared supported into ErrContract. Prepare branches on the declaration, so nothing falls back implicitly.
  • The checkpoint types and the typed setup errors move into the same file.
• Deleted:
  • CheckpointProvider, SelectionDiscoverer, CredentialVerifier and ConfigurationDiscoverer;
  • providerInterfaces, sandbox.Checkpoint() and the reflection Implements check;
  • all 28 casts;
  • the declaration rewrites in routers and node proxies.
• Observation.
  • runtimeobs owns the observation types, and imports stay one-way.
  • runtimeobs.NewService takes the deployment's Provider and its registered kind directly.
  • Deleted: ResolveObservationSource, SourceResolver and its one-entry map; ObserveBatch, BatchSource and readBatch. The batch path never ran in production, because routers redeclared it unsupported.
  • ObservationProviderType is deleted; every implementation returned the registered kind.
  • The E2B helper's observe request and response carry one reference, and MaxObservationReferences is gone.
• Quiescence. Quiescent is a declared field of the built generation, beside Probe and Close, set by the microsandbox builder. The anonymous Quiescent() assertions are gone.
• Docs.
  • docs/sandbox-provider.md (en/zh) describes the protocol and states the existing registration rule that checkpoint is admitted only for nodes-mode Providers.
  • runtime-observability*.md and the E2B helper README are updated.
  • AGENTS.md: the stale CheckpointProvider identifier now reads "the declared checkpoint lifecycle".

Behaviour

• Production paths are unchanged. E2B observation was already one target per read.
• source_not_configured now means only that this Core has no managed installation identity.
• An adapter that declares a setup operation supported but reports it unsupported gets ErrContract instead of being silently skipped.
• The generation router's observation identity check is deleted. It was unreachable: deployment.AllocationSetup already rejects a retained generation whose Provider differs from the current one, and the blind review verified this.

Review

A fresh-context blind review found no must-fix. Its verdict was "merge after fixes". Both should-fixes are fixed: the implicit fallback in prepare, and hand-kept operation lists with no test. So are the nits: the source_not_configured doc, a zero Selection on error, a Quiescent assertion, and the boundary wording.

Checks

• go build ./... and go vet ./....
• The 26 changed and dependent packages against the DB: 3078 passed, 0 failed. The 3 skips need a Docker fixture image.
• tests/integration: 722 passed.
• -race on sandbox/node, contractgen --check, and the E2B helper Python tests (180) and template tests (11).
• make openapi (no diff), TestCoreErrorCatalog, the translation test and check-names.

Net: non-test −474, tests −320, docs −10.

🤖 Generated with Claude Code

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}